object_class->set_property = st_adjustment_set_property;
object_class->dispose = st_adjustment_dispose;
+ /**
+ * StAdjustment:actor:
+ *
+ * If the adjustment is used as #ClutterAnimatable for a
+ * #ClutterPropertyTransition, this property is used to determine which
+ * monitor should drive the animation.
+ */
props[PROP_ACTOR] =
g_param_spec_object ("actor", "Actor", "Actor",
CLUTTER_TYPE_ACTOR,
ST_PARAM_READWRITE);
+ /**
+ * StAdjustment:lower:
+ *
+ * The minimum value of the adjustment.
+ */
props[PROP_LOWER] =
g_param_spec_double ("lower", "Lower", "Lower bound",
-G_MAXDOUBLE, G_MAXDOUBLE, 0.0,
G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * StAdjustment:upper:
+ *
+ * The maximum value of the adjustment.
+ *
+ * Note that values will be restricted by `upper - page-size` if
+ * #StAdjustment:page-size is non-zero.
+ */
props[PROP_UPPER] =
g_param_spec_double ("upper", "Upper", "Upper bound",
-G_MAXDOUBLE, G_MAXDOUBLE, 0.0,
G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * StAdjustment:value:
+ *
+ * The value of the adjustment.
+ */
props[PROP_VALUE] =
g_param_spec_double ("value", "Value", "Current value",
-G_MAXDOUBLE, G_MAXDOUBLE, 0.0,
G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * StAdjustment:step-increment:
+ *
+ * The step increment of the adjustment.
+ */
props[PROP_STEP_INC] =
g_param_spec_double ("step-increment", "Step Increment", "Step increment",
0.0, G_MAXDOUBLE, 0.0,
G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * StAdjustment:page-increment:
+ *
+ * The page increment of the adjustment.
+ */
props[PROP_PAGE_INC] =
g_param_spec_double ("page-increment", "Page Increment", "Page increment",
0.0, G_MAXDOUBLE, 0.0,
G_PARAM_CONSTRUCT |
G_PARAM_EXPLICIT_NOTIFY);
+ /**
+ * StAdjustment:page-size:
+ *
+ * The page size of the adjustment.
+ *
+ * Note that the page-size is irrelevant and should be set to zero if the
+ * adjustment is used for a simple scalar value.
+ */
props[PROP_PAGE_SIZE] =
g_param_spec_double ("page-size", "Page Size", "Page size",
0.0, G_MAXDOUBLE, 0.0,
priv->is_constructing = TRUE;
}
+/**
+ * st_adjustment_new:
+ * @actor: (nullable): a #ClutterActor
+ * @value: the initial value
+ * @lower: the minimum value
+ * @upper: the maximum value
+ * @step_increment: the step increment
+ * @page_increment: the page increment
+ * @page_size: the page size
+ *
+ * Creates a new #StAdjustment
+ *
+ * Returns: a new #StAdjustment
+ */
StAdjustment *
st_adjustment_new (ClutterActor *actor,
gdouble value,
NULL);
}
+/**
+ * st_adjustment_get_value:
+ * @adjustment: a #StAdjustment
+ *
+ * Gets the current value of the adjustment. See st_adjustment_set_value().
+ *
+ * Returns: The current value of the adjustment
+ */
gdouble
st_adjustment_get_value (StAdjustment *adjustment)
{
return ((StAdjustmentPrivate *)st_adjustment_get_instance_private (adjustment))->value;
}
+/**
+ * st_adjustment_set_value:
+ * @adjustment: a #StAdjustment
+ * @value: the new value
+ *
+ * Sets the #StAdjustment value. The value is clamped to lie between
+ * #StAdjustment:lower and #StAdjustment:upper - #StAdjustment:page-size.
+ */
void
st_adjustment_set_value (StAdjustment *adjustment,
gdouble value)
}
}
+/**
+ * st_adjustment_clamp_page:
+ * @adjustment: a #StAdjustment
+ * @lower: the lower value
+ * @upper: the upper value
+ *
+ * Set #StAdjustment:value to a value clamped between @lower and @upper. The
+ * clamping described by st_adjustment_set_value() still applies.
+ */
void
st_adjustment_clamp_page (StAdjustment *adjustment,
gdouble lower,
g_object_notify_by_pspec (G_OBJECT (adjustment), props[PROP_VALUE]);
}
+/**
+ * st_adjustment_set_lower:
+ * @adjustment: a #StAdjustment
+ * @lower: the new minimum value
+ *
+ * Sets the minimum value of the adjustment.
+ *
+ * When setting multiple adjustment properties via their individual
+ * setters, multiple #GObject::notify and #StAdjustment::changed
+ * signals will be emitted. However, it’s possible to compress the
+ * #GObject::notify signals into one by calling
+ * g_object_freeze_notify() and g_object_thaw_notify() around the
+ * calls to the individual setters.
+ *
+ * Alternatively, using st_adjustment_set_values() will compress both
+ * #GObject::notify and #StAdjustment::changed emissions.
+ */
static gboolean
st_adjustment_set_lower (StAdjustment *adjustment,
gdouble lower)
return FALSE;
}
+/**
+ * st_adjustment_set_upper:
+ * @adjustment: a #StAdjustment
+ * @upper: the new maximum value
+ *
+ * Sets the maximum value of the adjustment.
+ *
+ * Note that values will be restricted by `upper - page-size`
+ * if the page-size property is nonzero.
+ *
+ * See st_adjustment_set_lower() about how to compress multiple
+ * signal emissions when setting multiple adjustment properties.
+ *
+ * Returns: %TRUE if the value was changed
+ */
static gboolean
st_adjustment_set_upper (StAdjustment *adjustment,
gdouble upper)
return FALSE;
}
+/**
+ * st_adjustment_set_step_increment:
+ * @adjustment: a #StAdjustment
+ * @step: the new step increment
+ *
+ * Sets the step increment of the adjustment.
+ *
+ * See st_adjustment_set_lower() about how to compress multiple
+ * signal emissions when setting multiple adjustment properties.
+ *
+ * Returns: %TRUE if the value was changed
+ */
static gboolean
st_adjustment_set_step_increment (StAdjustment *adjustment,
gdouble step)
return FALSE;
}
+/**
+ * st_adjustment_set_page_increment:
+ * @adjustment: a #StAdjustment
+ * @page: the new page increment
+ *
+ * Sets the page increment of the adjustment.
+ *
+ * See st_adjustment_set_lower() about how to compress multiple
+ * signal emissions when setting multiple adjustment properties.
+ *
+ * Returns: %TRUE if the value was changed
+ */
static gboolean
st_adjustment_set_page_increment (StAdjustment *adjustment,
gdouble page)
return FALSE;
}
+/**
+ * st_adjustment_set_page_size:
+ * @adjustment: a #StAdjustment
+ * @size: the new page size
+ *
+ * Sets the page size of the adjustment.
+ *
+ * See st_adjustment_set_lower() about how to compress multiple
+ * signal emissions when setting multiple adjustment properties.
+ *
+ * Returns: %TRUE if the value was changed
+ */
static gboolean
st_adjustment_set_page_size (StAdjustment *adjustment,
gdouble size)
return FALSE;
}
+/**
+ * st_adjustment_set_values:
+ * @adjustment: a #StAdjustment
+ * @value: the new value
+ * @lower: the new minimum value
+ * @upper: the new maximum value
+ * @step_increment: the new step increment
+ * @page_increment: the new page increment
+ * @page_size: the new page size
+ *
+ * Sets all properties of the adjustment at once.
+ *
+ * Use this function to avoid multiple emissions of the #GObject::notify and
+ * #StAdjustment::changed signals. See st_adjustment_set_lower() for an
+ * alternative way of compressing multiple emissions of #GObject::notify into
+ * one.
+ */
void
st_adjustment_set_values (StAdjustment *adjustment,
gdouble value,
/**
* st_adjustment_get_values:
* @adjustment: an #StAdjustment
- * @value: (out): the current value
- * @lower: (out): the lower bound
- * @upper: (out): the upper bound
- * @step_increment: (out): the step increment
- * @page_increment: (out): the page increment
- * @page_size: (out): the page size
+ * @value: (out) (optional): the current value
+ * @lower: (out) (optional): the lower bound
+ * @upper: (out) (optional): the upper bound
+ * @step_increment: (out) (optional): the step increment
+ * @page_increment: (out) (optional): the page increment
+ * @page_size: (out) (optional): the page size
*
* Gets all of @adjustment's values at once.
*/
/**
* st_adjustment_get_transition:
- * Returns: (transfer none) (nullable):
+ * @adjustment: a #StAdjustment
+ * @name: a transition name
+ *
+ * Get the #ClutterTransition for @name previously added with
+ * st_adjustment_add_transition() or %NULL if not found.
+ *
+ * Returns: (transfer none) (nullable): a #ClutterTransition
*/
ClutterTransition *
st_adjustment_get_transition (StAdjustment *adjustment,
return clos->transition;
}
+/**
+ * st_adjustment_add_transition:
+ * @adjustment: a #StAdjustment
+ * @name: a unique name for the transition
+ * @transtion: a #ClutterTransition
+ *
+ * Add a #ClutterTransition for the adjustment. If the transiton stops, it will
+ * be automatically removed if #ClutterTransition:remove-on-complete is %TRUE.
+ */
void
st_adjustment_add_transition (StAdjustment *adjustment,
const char *name,
clutter_timeline_start (CLUTTER_TIMELINE (transition));
}
+/**
+ * st_adjusmtent_remove_transition:
+ * @adjusment: a #StAdjustment
+ * @name: the name of the transition to remove
+ *
+ * Remove a #ClutterTransition previously added by st_adjustment_add_transtion()
+ * with @name.
+ */
void
st_adjustment_remove_transition (StAdjustment *adjustment,
const char *name)
*
* Creates a new #StBin, a simple container for one child.
*
- * Return value: the newly created #StBin actor
+ * Returns: the newly created #StBin actor
*/
StWidget *
st_bin_new (void)
* st_bin_get_child:
* @bin: a #StBin
*
- * Retrieves a pointer to the child of @bin.
+ * Gets the #ClutterActor child for @bin.
*
- * Return value: (transfer none): a #ClutterActor, or %NULL
+ * Returns: (transfer none) (nullable): a #ClutterActor, or %NULL
*/
ClutterActor *
st_bin_get_child (StBin *bin)
{
}
+/**
+ * st_border_image_new:
+ * @file: a #GFile
+ * @border_top: the top border
+ * @border_right: the right border
+ * @border_bottom: the bottom border
+ * @border_left: the left border
+ * @scale_factor: the scale factor
+ *
+ * Creates a new #StBorderImage.
+ *
+ * Returns: a new #StBorderImage.
+ */
StBorderImage *
st_border_image_new (GFile *file,
int border_top,
/**
* st_border_image_get_file:
- * @image: a #StBorder_Image
+ * @image: a #StBorderImage
*
- * Returns: (transfer none): the #GFile for the #StBorder_Image
+ * Get the #GFile for @image.
+ *
+ * Returns: (transfer none): a #GFile
*/
GFile *
st_border_image_get_file (StBorderImage *image)
return image->file;
}
+/**
+ * st_border_image_get_border:
+ * @image: a #StBorderImage
+ * @border_top: (out) (optional): the top border
+ * @border_right: (out) (optional): the right border
+ * @border_bottom: (out) (optional): the bottom border
+ * @border_left: (out) (optional): the left border
+ *
+ * Get the border widths for @image, taking into account the scale factor
+ * provided at construction.
+ */
void
st_border_image_get_borders (StBorderImage *image,
int *border_top,
/**
* st_border_image_equal:
- * @image: a #StBorder_Image
- * @other: a different #StBorder_Image
+ * @image: a #StBorderImage
+ * @other: a different #StBorderImage
*
- * Check if two border_image objects are identical.
+ * Check if two #StBorderImage objects are identical.
*
- * Return value: %TRUE if the two border image objects are identical
+ * Returns: %TRUE if the two border image objects are identical
*/
gboolean
st_border_image_equal (StBorderImage *image,
/**
* StBoxLayout:vertical:
*
- * A convenience property for getting the #ClutterBoxLayout:vertical
- * property of the layout for #StBoxLayout.
+ * A convenience property for the #ClutterBoxLayout:vertical property of the
+ * internal layout for #StBoxLayout.
*/
pspec = g_param_spec_boolean ("vertical",
"Vertical",
/**
* StBoxLayout:pack-start:
*
- * A convenience property for getting the #ClutterBoxLayout:pack-start
- * property of the layout for #StBoxLayout.
+ * A convenience property for the #ClutterBoxLayout:pack-start property of the
+ * internal layout for #StBoxLayout.
*/
pspec = g_param_spec_boolean ("pack-start",
"Pack Start",
widget_class->style_changed = st_button_style_changed;
widget_class->get_accessible_type = st_button_accessible_get_type;
+ /**
+ * StButton:label:
+ *
+ * The label of the #StButton.
+ */
props[PROP_LABEL] =
g_param_spec_string ("label",
"Label",
NULL,
ST_PARAM_READWRITE);
+ /**
+ * StButton:button-mask:
+ *
+ * Which buttons will trigger the #StButton::clicked signal.
+ */
props[PROP_BUTTON_MASK] =
g_param_spec_flags ("button-mask",
"Button mask",
ST_TYPE_BUTTON_MASK, ST_BUTTON_ONE,
ST_PARAM_READWRITE);
+ /**
+ * StButton:toggle-mode:
+ *
+ * Whether the #StButton is operating in toggle mode (on/off).
+ */
props[PROP_TOGGLE_MODE] =
g_param_spec_boolean ("toggle-mode",
"Toggle Mode",
FALSE,
ST_PARAM_READWRITE);
+ /**
+ * StButton:checked:
+ *
+ * If #StButton:toggle-mode is %TRUE, indicates if the #StButton is toggled
+ * "on" or "off".
+ *
+ * When the value is %TRUE, the #StButton will have the `checked` CSS
+ * pseudo-class set.
+ */
props[PROP_CHECKED] =
g_param_spec_boolean ("checked",
"Checked",
FALSE,
ST_PARAM_READWRITE);
+ /**
+ * StButton:pressed:
+ *
+ * In contrast to #StButton:checked, this property indicates whether the
+ * #StButton is being actively pressed, rather than just in the "on" state.
+ */
props[PROP_PRESSED] =
g_param_spec_boolean ("pressed",
"Pressed",
* st_button_get_label:
* @button: a #StButton
*
- * Get the text displayed on the button
+ * Get the text displayed on the button. If the label is empty, an empty string
+ * will be returned instead of %NULL.
*
- * Returns: the text for the button. This must not be freed by the application
+ * Returns: (transfer none): the text for the button
*/
const gchar *
st_button_get_label (StButton *button)
/**
* st_button_set_label:
* @button: a #Stbutton
- * @text: text to set the label to
+ * @text: (nullable): text to set the label to
*
- * Sets the text displayed on the button
+ * Sets the text displayed on the button.
*/
void
st_button_set_label (StButton *button,
* st_button_get_checked:
* @button: a #StButton
*
- * Get the state of the button that is in toggle mode.
+ * Get the #StButton:checked property of a #StButton that is in toggle mode.
*
* Returns: %TRUE if the button is checked, or %FALSE if not
*/
* @button: a #Stbutton
* @checked: %TRUE or %FALSE
*
- * Sets the pressed state of the button. This is only really useful if the
- * button has #toggle-mode mode set to %TRUE.
+ * Set the #StButton:checked property of the button. This is only really useful
+ * if the button has #StButton:toggle-mode property set to %TRUE.
*/
void
st_button_set_checked (StButton *button,
* @button: an #StButton
*
* If this widget is holding a pointer grab, this function will
- * will ungrab it, and reset the pressed state. The effect is
+ * will ungrab it, and reset the #StButton:pressed state. The effect is
* similar to if the user had released the mouse button, but without
- * emitting the clicked signal.
+ * emitting the #StButton::clicked signal.
*
* This function is useful if for example you want to do something
* after the user is holding the mouse button for a given period of
* @ST_BUTTON_TWO: button 2 (middle)
* @ST_BUTTON_THREE: button 3 (right)
*
- * A mask representing which mouse buttons an StButton responds to.
+ * A mask representing which mouse buttons an #StButton responds to.
*/
typedef enum {
ST_BUTTON_ONE = (1 << 0),
*
* Request the data from the clipboard in text form. @callback is executed
* when the data is retreived.
- *
*/
void
st_clipboard_get_text (StClipboard *clipboard,
*
* Request the data from the clipboard in #GBytes form. @callback is executed
* when the data is retrieved.
- *
*/
void
st_clipboard_get_content (StClipboard *clipboard,
* @mimetype: content mimetype
* @bytes: content data
*
- * Sets the clipboard content.
+ * Sets the clipboard content to @bytes.
+ *
+ * @mimetype is a semi-colon separated list of mime-type strings.
**/
void
st_clipboard_set_content (StClipboard *clipboard,
g_bytes_unref (bytes);
}
+/**
+ * st_clipboard_set_selection: (skip)
+ *
+ * Sets the #MetaSelection of the default #StClipboard.
+ *
+ * This function is called during the initialization of GNOME Shell.
+ */
void
st_clipboard_set_selection (MetaSelection *selection)
{
* st_drawing_area_queue_repaint:
* @area: the #StDrawingArea
*
- * Will cause the actor to emit a ::repaint signal before it is next
- * drawn to the scene. Useful if some parameters for the area being
+ * Will cause the actor to emit a #StDrawingArea::repaint signal before it is
+ * next drawn to the scene. Useful if some parameters for the area being
* drawn other than the size or style have changed. Note that
* clutter_actor_queue_redraw() will simply result in the same
* contents being drawn to the scene again.
* @area: the #StDrawingArea
*
* Gets the Cairo context to paint to. This function must only be called
- * from a signal hander for the ::repaint signal.
+ * from a signal hander or virtual function for the #StDrawingArea::repaint
+ * signal.
*
- * Return Value: (transfer none): the Cairo context for the paint operation
+ * JavaScript code must call the special dispose function before returning from
+ * the signal handler or virtual function to avoid leaking memory:
+ *
+ * |[<!-- language="JavaScript" -->
+ * function onRepaint(area) {
+ * let cr = area.get_context();
+ *
+ * // Draw to the context
+ *
+ * cr.$dispose();
+ * }
+ *
+ * let area = new St.DrawingArea();
+ * area.connect('repaint', onRepaint);
+ * ]|
+ *
+ * Returns: (transfer none): the Cairo context for the paint operation
*/
cairo_t *
st_drawing_area_get_context (StDrawingArea *area)
/**
* st_drawing_area_get_surface_size:
* @area: the #StDrawingArea
- * @width: (out): location to store the width of the painted area
- * @height: (out): location to store the height of the painted area
+ * @width: (out) (optional): location to store the width of the painted area
+ * @height: (out) (optional): location to store the height of the painted area
*
* Gets the size of the cairo surface being painted to, which is equal
* to the size of the content area of the widget. This function must
- * only be called from a signal hander for the ::repaint signal.
+ * only be called from a signal hander for the #StDrawingArea::repaint signal.
*/
void
st_drawing_area_get_surface_size (StDrawingArea *area,
* applications to set further properties.
*
* #StEntry supports the following pseudo style states:
- * <itemizedlist>
- * <listitem>
- * <para>focus: the widget has focus</para>
- * </listitem>
- * <listitem>
- * <para>indeterminate: the widget is showing the hint text or actor</para>
- * </listitem>
- * </itemizedlist>
+ *
+ * - `focus`: the widget has focus
+ * - `indeterminate`: the widget is showing the hint text or actor
*/
#ifdef HAVE_CONFIG_H
widget_class->navigate_focus = st_entry_navigate_focus;
widget_class->get_accessible_type = st_entry_accessible_get_type;
+ /**
+ * StEntry:clutter-text:
+ *
+ * The internal #ClutterText actor supporting the #StEntry.
+ */
props[PROP_CLUTTER_TEXT] =
g_param_spec_object ("clutter-text",
"Clutter Text",
CLUTTER_TYPE_TEXT,
ST_PARAM_READABLE);
+ /**
+ * StEntry:primary-icon:
+ *
+ * The #ClutterActor acting as the primary icon at the start of the #StEntry.
+ */
props[PROP_PRIMARY_ICON] =
g_param_spec_object ("primary-icon",
"Primary Icon",
CLUTTER_TYPE_ACTOR,
ST_PARAM_READWRITE);
+ /**
+ * StEntry:secondary-icon:
+ *
+ * The #ClutterActor acting as the secondary icon at the end of the #StEntry.
+ */
props[PROP_SECONDARY_ICON] =
g_param_spec_object ("secondary-icon",
"Secondary Icon",
CLUTTER_TYPE_ACTOR,
ST_PARAM_READWRITE);
+ /**
+ * StEntry:hint-text:
+ *
+ * The text to display when the entry is empty and unfocused. Setting this
+ * will replace the actor of #StEntry::hint-actor.
+ */
props[PROP_HINT_TEXT] =
g_param_spec_string ("hint-text",
"Hint Text",
NULL,
ST_PARAM_READWRITE);
+ /**
+ * StEntry:hint-actor:
+ *
+ * A #ClutterActor to display when the entry is empty and unfocused. Setting
+ * this will replace the actor displaying #StEntry:hint-text.
+ */
props[PROP_HINT_ACTOR] =
g_param_spec_object ("hint-actor",
"Hint Actor",
CLUTTER_TYPE_ACTOR,
ST_PARAM_READWRITE);
+ /**
+ * StEntry:text:
+ *
+ * The current text value of the #StEntry.
+ */
props[PROP_TEXT] =
g_param_spec_string ("text",
"Text",
NULL,
ST_PARAM_READWRITE);
+ /**
+ * StEntry:input-purpose:
+ *
+ * The #ClutterInputContentPurpose that helps on-screen keyboards and similar
+ * input methods to decide which keys should be presented to the user.
+ */
props[PROP_INPUT_PURPOSE] =
g_param_spec_enum ("input-purpose",
"Purpose",
CLUTTER_INPUT_CONTENT_PURPOSE_NORMAL,
ST_PARAM_READWRITE);
+ /**
+ * StEntry:input-hints:
+ *
+ * The #ClutterInputContentHintFlags providing additional hints (beyond
+ * #StEntry:input-purpose) that allow input methods to fine-tune their
+ * behaviour.
+ */
props[PROP_INPUT_HINTS] =
g_param_spec_flags ("input-hints",
"hints",
* StEntry::primary-icon-clicked:
* @self: the #StEntry
*
- *
- * Emitted when the primary icon is clicked
+ * Emitted when the primary icon is clicked.
*/
entry_signals[PRIMARY_ICON_CLICKED] =
g_signal_new ("primary-icon-clicked",
G_STRUCT_OFFSET (StEntryClass, primary_icon_clicked),
NULL, NULL, NULL,
G_TYPE_NONE, 0);
+
/**
* StEntry::secondary-icon-clicked:
* @self: the #StEntry
*
- * Emitted when the secondary icon is clicked
+ * Emitted when the secondary icon is clicked.
*/
entry_signals[SECONDARY_ICON_CLICKED] =
g_signal_new ("secondary-icon-clicked",
/**
* st_entry_new:
- * @text: text to set the entry to
+ * @text: (nullable): text to set the entry to
*
- * Create a new #StEntry with the specified entry
+ * Create a new #StEntry with the specified text.
*
* Returns: a new #StEntry
*/
* st_entry_get_text:
* @entry: a #StEntry
*
- * Get the text displayed on the entry
+ * Get the text displayed on the entry. If @entry is empty, an empty string will
+ * be returned instead of %NULL.
*
- * Returns: the text for the entry. This must not be freed by the application
+ * Returns: (transfer none): the text for the entry
*/
const gchar *
st_entry_get_text (StEntry *entry)
* @entry: a #StEntry
* @text: (nullable): text to set the entry to
*
- * Sets the text displayed on the entry
+ * Sets the text displayed on the entry. If @text is %NULL, the #ClutterText
+ * will instead be set to an empty string.
*/
void
st_entry_set_text (StEntry *entry,
* st_entry_get_clutter_text:
* @entry: a #StEntry
*
- * Retrieve the internal #ClutterText so that extra parameters can be set
+ * Retrieve the internal #ClutterText so that extra parameters can be set.
*
- * Returns: (transfer none): the #ClutterText used by #StEntry. The entry is
- * owned by the #StEntry and should not be unref'ed by the application.
+ * Returns: (transfer none): the #ClutterText used by @entry
*/
ClutterActor*
st_entry_get_clutter_text (StEntry *entry)
* @text: (nullable): text to set as the entry hint
*
* Sets the text to display when the entry is empty and unfocused. When the
- * entry is displaying the hint, it has a pseudo class of "indeterminate".
- * A value of NULL unsets the hint.
+ * entry is displaying the hint, it has a pseudo class of `indeterminate`.
+ * A value of %NULL unsets the hint.
*/
void
st_entry_set_hint_text (StEntry *entry,
* st_entry_get_hint_text:
* @entry: a #StEntry
*
- * Gets the text that is displayed when the entry is empty and unfocused
+ * Gets the text that is displayed when the entry is empty and unfocused or
+ * %NULL if the #StEntry:hint-actor was set to an actor that is not a #StLabel.
*
- * Returns: the current value of the hint property. This string is owned by the
- * #StEntry and should not be freed or modified.
+ * Unlike st_entry_get_text() this function may return %NULL if
+ * #StEntry:hint-actor is not a #StLabel.
+ *
+ * Returns: (nullable) (transfer none): the current value of the hint property
*/
const gchar *
st_entry_get_hint_text (StEntry *entry)
* @entry: a #StEntry
*
* Gets the value of the #StEntry:input-purpose property.
+ *
+ * Returns: the input purpose of the entry
*/
ClutterInputContentPurpose
st_entry_get_input_purpose (StEntry *entry)
* @entry: a #StEntry
*
* Gets the value of the #StEntry:input-hints property.
+ *
+ * Returns: the input hints for the entry
*/
ClutterInputContentHintFlags
st_entry_get_input_hints (StEntry *entry)
* @entry: a #StEntry
* @icon: (nullable): a #ClutterActor
*
- * Set the primary icon of the entry to @icon
+ * Set the primary icon of the entry to @icon.
*/
void
st_entry_set_primary_icon (StEntry *entry,
* st_entry_get_primary_icon:
* @entry: a #StEntry
*
- * Returns: (transfer none): a #ClutterActor
+ * Get the value of the #StEntry:primary-icon property.
+ *
+ * Returns: (nullable) (transfer none): a #ClutterActor
*/
ClutterActor *
st_entry_get_primary_icon (StEntry *entry)
* @entry: a #StEntry
* @icon: (nullable): an #ClutterActor
*
- * Set the secondary icon of the entry to @icon
+ * Set the secondary icon of the entry to @icon.
*/
void
st_entry_set_secondary_icon (StEntry *entry,
* st_entry_get_secondary_icon:
* @entry: a #StEntry
*
- * Returns: (transfer none): a #ClutterActor
+ * Get the value of the #StEntry:secondary-icon property.
+ *
+ * Returns: (nullable) (transfer none): a #ClutterActor
*/
ClutterActor *
st_entry_get_secondary_icon (StEntry *entry)
/**
* st_entry_set_hint_actor:
* @entry: a #StEntry
- * @hint_actor: (allow-none): a #ClutterActor
+ * @hint_actor: (nullable): a #ClutterActor
*
- * Set the hint actor of the entry to @hint_actor
+ * Set the hint actor of the entry to @hint_actor.
*/
void
st_entry_set_hint_actor (StEntry *entry,
* st_entry_get_hint_actor:
* @entry: a #StEntry
*
- * Returns: (transfer none): a #ClutterActor
+ * Get the value of the #StEntry:hint-actor property.
+ *
+ * Returns: (nullable) (transfer none): a #ClutterActor
*/
ClutterActor *
st_entry_get_hint_actor (StEntry *entry)
*
* Gets the #StFocusManager for @stage, creating it if necessary.
*
- * Return value: (transfer none): the focus manager for @stage
+ * Returns: (transfer none): the focus manager for @stage
*/
StFocusManager *
st_focus_manager_get_for_stage (ClutterStage *stage)
* Checks if @widget is inside a focus group, and if so, returns
* the root of that group.
*
- * Return value: (transfer none): the focus group root, or %NULL if
+ * Returns: (transfer none): the focus group root, or %NULL if
* @widget is not in a focus group
*/
StWidget *
* @self. Right now we only care about doubles, so the value is
* directly returned by the signal.
*
- * Return value: value of the current element.
+ * Returns: value of the current element.
*/
st_generic_accessible_signals[GET_CURRENT_VALUE] =
g_signal_new ("get-current-value",
* @self. Right now we only care about doubles, so the value is
* directly returned by the signal.
*
- * Return value: maximum value of the accessible.
+ * Returns: maximum value of the accessible.
*/
st_generic_accessible_signals[GET_MAXIMUM_VALUE] =
g_signal_new ("get-maximum-value",
* @self. Right now we only care about doubles, so the value is
* directly returned by the signal.
*
- * Return value: minimum value of the accessible.
+ * Returns: minimum value of the accessible.
*/
st_generic_accessible_signals[GET_MINIMUM_VALUE] =
g_signal_new ("get-minimum-value",
* @self. Right now we only care about doubles, so the value is
* directly returned by the signal.
*
- * Return value: value of the current element.
+ * Returns: value of the current element.
*/
st_generic_accessible_signals[GET_MINIMUM_INCREMENT] =
g_signal_new ("get-minimum-increment",
iface->set_current_value = st_generic_accessible_set_current_value;
}
+/**
+ * st_generic_accessible_new_for_actor:
+ * @actor: a #Clutter Actor
+ *
+ * Create a new #StGenericAccessible for @actor.
+ *
+ * This is useful only for custom widgets that need a proxy for #AtkObject.
+ *
+ * Returns: (transfer full): a new #AtkObject
+ */
AtkObject*
st_generic_accessible_new_for_actor (ClutterActor *actor)
{
*
* Creates a new #StIconColors. All colors are initialized to transparent black.
*
- * Return value: a newly created #StIconColors. Free with st_icon_colors_unref()
+ * Returns: a newly created #StIconColors. Free with st_icon_colors_unref()
*/
StIconColors *
st_icon_colors_new (void)
* @colors: a #StIconColors
* @other: another #StIconColors
*
+ * Check if two #StIconColors objects are identical.
+ *
* Returns: %TRUE if the #StIconColors are equal
*/
gboolean
widget_class->style_changed = st_icon_style_changed;
actor_class->resource_scale_changed = st_icon_resource_scale_changed;
+ /**
+ * StIcon:gicon:
+ *
+ * The #GIcon being displayed by this #StIcon.
+ */
props[PROP_GICON] =
g_param_spec_object ("gicon",
"GIcon",
G_TYPE_ICON,
ST_PARAM_READWRITE);
+ /**
+ * StIcon:fallback-gicon:
+ *
+ * The fallback #GIcon to display if #StIcon:gicon fails to load.
+ */
props[PROP_FALLBACK_GICON] =
g_param_spec_object ("fallback-gicon",
"Fallback GIcon",
G_TYPE_ICON,
ST_PARAM_READWRITE);
+ /**
+ * StIcon:icon-name:
+ *
+ * The name of the icon if the icon being displayed is a #GThemedIcon.
+ */
props[PROP_ICON_NAME] =
g_param_spec_string ("icon-name",
"Icon name",
NULL,
ST_PARAM_READWRITE);
+ /**
+ * StIcon:icon-size:
+ *
+ * The size of the icon, if greater than `0`. Other the icon sise is derived
+ * from the current style.
+ */
props[PROP_ICON_SIZE] =
g_param_spec_int ("icon-size",
"Icon size",
-1, G_MAXINT, -1,
ST_PARAM_READWRITE);
+ /**
+ * StIcon:fallback-icon-name:
+ *
+ * The fallback icon name of the #StIcon. See st_icon_set_fallback_icon_name()
+ * for details.
+ */
props[PROP_FALLBACK_ICON_NAME] =
g_param_spec_string ("fallback-icon-name",
"Fallback icon name",
/**
* st_icon_new:
*
- * Create a newly allocated #StIcon
+ * Create a newly allocated #StIcon.
*
* Returns: A newly allocated #StIcon
*/
* st_icon_get_icon_name:
* @icon: an #StIcon
*
- * This is a convenience method to get the icon name of the #GThemedIcon that
- * is currently set.
+ * This is a convenience method to get the icon name of the current icon, if it
+ * is currenyly a #GThemedIcon, or %NULL otherwise.
*
- * Returns: (transfer none): The name of the icon or %NULL if no icon is set
+ * Returns: (transfer none) (nullable): The name of the icon or %NULL
*/
const gchar *
st_icon_get_icon_name (StIcon *icon)
*
* Gets the current #GIcon in use.
*
- * Returns: (transfer none): The current #GIcon, if set, otherwise %NULL
+ * Returns: (nullable) (transfer none): The current #GIcon, if set, otherwise %NULL
*/
GIcon *
st_icon_get_gicon (StIcon *icon)
*
* Creates a new #StImageContent, a simple content for sized images.
*
- * Return value: (transfer full): the newly created #StImageContent content
+ * See #ClutterImage for setting the actual image to display or #StIcon for
+ * displaying icons.
+ *
+ * Returns: (transfer full): the newly created #StImageContent content
* Use g_object_unref() when done.
*/
ClutterContent *
widget_class->style_changed = st_label_style_changed;
widget_class->get_accessible_type = st_label_accessible_get_type;
+ /**
+ * StLabel:clutter-text:
+ *
+ * The internal #ClutterText actor supporting the label
+ */
props[PROP_CLUTTER_TEXT] =
g_param_spec_object ("clutter-text",
"Clutter Text",
CLUTTER_TYPE_TEXT,
ST_PARAM_READABLE);
+ /**
+ * StLabel:text:
+ *
+ * The current text being display in the #StLabel.
+ */
props[PROP_TEXT] =
g_param_spec_string ("text",
"Text",
/**
* st_label_new:
- * @text: text to set the label to
+ * @text: (nullable): text to set the label to
*
- * Create a new #StLabel with the specified label
+ * Create a new #StLabel with the label specified by @text.
*
* Returns: a new #StLabel
*/
* st_label_get_text:
* @label: a #StLabel
*
- * Get the text displayed on the label
+ * Get the text displayed on the label.
*
- * Returns: the text for the label. This must not be freed by the application
+ * Returns: (transfer none): the text for the label. This must not be freed by
+ * the application
*/
const gchar *
st_label_get_text (StLabel *label)
/**
* st_label_set_text:
* @label: a #StLabel
- * @text: text to set the label to
+ * @text: (nullable): text to set the label to
*
- * Sets the text displayed on the label
+ * Sets the text displayed by the label.
*/
void
st_label_set_text (StLabel *label,
* st_label_get_clutter_text:
* @label: a #StLabel
*
- * Retrieve the internal #ClutterText so that extra parameters can be set
+ * Retrieve the internal #ClutterText used by @label so that extra parameters
+ * can be set.
*
- * Returns: (transfer none): ethe #ClutterText used by #StLabel. The label
- * is owned by the #StLabel and should not be unref'ed by the application.
+ * Returns: (transfer none): the #ClutterText used by #StLabel. The actor
+ * is owned by the #StLabel and should not be destroyed by the application.
*/
ClutterActor*
st_label_get_clutter_text (StLabel *label)
st_entry_class->secondary_icon_clicked = st_password_entry_secondary_icon_clicked;
+ /**
+ * StPasswordEntry:password-visible:
+ *
+ * Whether the text in the entry is masked for privacy.
+ */
props[PROP_PASSWORD_VISIBLE] = g_param_spec_boolean ("password-visible",
"Password visible",
- "Whether to text in the entry is masked or not",
+ "Whether the text in the entry is masked or not",
FALSE,
ST_PARAM_READWRITE);
+ /**
+ * StPasswordEntry:show-peek-icon:
+ *
+ * Whether to display an icon button to toggle the masking enabled by the
+ * #StPasswordEntry:password-visible property.
+ */
props[PROP_SHOW_PEEK_ICON] = g_param_spec_boolean ("show-peek-icon",
"Show peek icon",
"Whether to show the password peek icon",
/**
* st_password_entry_set_show_peek_icon:
* @entry: a #StPasswordEntry
- * @value: #TRUE to show the peek-icon in the entry, #FALSE otherwise
+ * @value: %TRUE to show the peek-icon in the entry
*
- * Sets whether to show or hide the peek-icon in the password entry.
+ * Sets whether to show or hide the peek-icon in the password entry. If %TRUE,
+ * a icon button for temporarily unmasking the password will be shown at the
+ * end of the entry.
*/
void
-st_password_entry_set_show_peek_icon (StPasswordEntry *entry, gboolean value)
+st_password_entry_set_show_peek_icon (StPasswordEntry *entry,
+ gboolean value)
{
StPasswordEntryPrivate *priv;
* @entry: a #StPasswordEntry
*
* Gets whether peek-icon is shown or hidden in the password entry.
+ *
+ * Returns: %TRUE if visible
*/
gboolean
st_password_entry_get_show_peek_icon (StPasswordEntry *entry)
/**
* st_password_entry_set_password_visible:
* @entry: a #StPasswordEntry
- * @value: #TRUE to show the password in the entry, #FALSE otherwise
+ * @value: %TRUE to show the password in the entry, #FALSE otherwise
*
* Sets whether to show or hide text in the password entry.
*/
void
-st_password_entry_set_password_visible (StPasswordEntry *entry, gboolean value)
+st_password_entry_set_password_visible (StPasswordEntry *entry,
+ gboolean value)
{
StPasswordEntryPrivate *priv;
ClutterActor *clutter_text;
* @entry: a #StPasswordEntry
*
* Gets whether the text is masked in the password entry.
+ *
+ * Returns: %TRUE if visible
*/
gboolean
st_password_entry_get_password_visible (StPasswordEntry *entry)
widget_class->style_changed = st_scroll_bar_style_changed;
+ /**
+ * StScrollBar:adjustment:
+ *
+ * The #StAdjustment controlling the #StScrollBar.
+ */
props[PROP_ADJUSTMENT] =
g_param_spec_object ("adjustment", "Adjustment", "The adjustment",
ST_TYPE_ADJUSTMENT,
ST_PARAM_READWRITE);
+ /**
+ * StScrollBar:vertical:
+ *
+ * Whether the #StScrollBar is vertical. If %FALSE it is horizontal.
+ */
props[PROP_VERTICAL] =
g_param_spec_boolean ("vertical",
"Vertical Orientation",
g_object_class_install_properties (object_class, N_PROPS, props);
+
+ /**
+ * StScrollBar::scroll-start:
+ * @bar: a #StScrollBar
+ *
+ * Emitted when the #StScrollBar begins scrolling.
+ */
signals[SCROLL_START] =
g_signal_new ("scroll-start",
G_TYPE_FROM_CLASS (klass),
NULL, NULL, NULL,
G_TYPE_NONE, 0);
+ /**
+ * StScrollBar::scroll-stop:
+ * @bar: a #StScrollBar
+ *
+ * Emitted when the #StScrollBar finishes scrolling.
+ */
signals[SCROLL_STOP] =
g_signal_new ("scroll-stop",
G_TYPE_FROM_CLASS (klass),
* st_scroll_bar_get_adjustment:
* @bar: a #StScrollbar
*
- * Gets the adjustment object that stores the current position
- * of the scrollbar.
+ * Gets the #StAdjustment that controls the current position of @bar.
*
- * Return value: (transfer none): the adjustment
+ * Returns: (transfer none): an #StAdjustment
*/
StAdjustment *
st_scroll_bar_get_adjustment (StScrollBar *bar)
offscreen_class->create_texture = st_scroll_view_fade_create_texture;
offscreen_class->paint_target = st_scroll_view_fade_paint_target;
+ /**
+ * StScrollViewFade:vfade-offset:
+ *
+ * The height of area which is faded at the top and bottom edges of the
+ * #StScrollViewFade.
+ */
props[PROP_VFADE_OFFSET] =
g_param_spec_float ("vfade-offset",
"Vertical Fade Offset",
0.f, G_MAXFLOAT, DEFAULT_FADE_OFFSET,
ST_PARAM_READWRITE);
+ /**
+ * StScrollViewFade:hfade-offset:
+ *
+ * The height of area which is faded at the left and right edges of the
+ * #StScrollViewFade.
+ */
props[PROP_HFADE_OFFSET] =
g_param_spec_float ("hfade-offset",
"Horizontal Fade Offset",
0.f, G_MAXFLOAT, DEFAULT_FADE_OFFSET,
ST_PARAM_READWRITE);
+ /**
+ * StScrollViewFade:fade-edges:
+ *
+ * Whether the faded area should extend to the edges of the #StScrollViewFade.
+ */
props[PROP_FADE_EDGES] =
g_param_spec_boolean ("fade-edges",
"Fade Edges",
self->hfade_offset = DEFAULT_FADE_OFFSET;
}
+/**
+ * st_scroll_view_fade_new:
+ *
+ * Create a new #StScrollViewFade.
+ *
+ * Returns: (transfer full): a new #StScrollViewFade
+ */
ClutterEffect *
st_scroll_view_fade_new (void)
{
*/
void
st_scroll_view_update_fade_effect (StScrollView *scroll,
- float vfade_offset,
- float hfade_offset)
+ float vfade_offset,
+ float hfade_offset)
{
StScrollViewPrivate *priv = ST_SCROLL_VIEW (scroll)->priv;
widget_class->style_changed = st_scroll_view_style_changed;
+ /**
+ * StScrollView:hscroll:
+ *
+ * The horizontal #StScrollBar for the #StScrollView.
+ */
props[PROP_HSCROLL] =
g_param_spec_object ("hscroll",
"StScrollBar",
ST_TYPE_SCROLL_BAR,
ST_PARAM_READABLE);
+ /**
+ * StScrollView:vscroll:
+ *
+ * The vertical #StScrollBar for the #StScrollView.
+ */
props[PROP_VSCROLL] =
g_param_spec_object ("vscroll",
"StScrollBar",
ST_TYPE_SCROLL_BAR,
ST_PARAM_READABLE);
+ /**
+ * StScrollView:vscrollbar-policy:
+ *
+ * The #StPolicyType for when to show the vertical #StScrollBar.
+ */
props[PROP_VSCROLLBAR_POLICY] =
g_param_spec_enum ("vscrollbar-policy",
"Vertical Scrollbar Policy",
ST_POLICY_AUTOMATIC,
ST_PARAM_READWRITE);
+ /**
+ * StScrollView:hscrollbar-policy:
+ *
+ * The #StPolicyType for when to show the horizontal #StScrollBar.
+ */
props[PROP_HSCROLLBAR_POLICY] =
g_param_spec_enum ("hscrollbar-policy",
"Horizontal Scrollbar Policy",
ST_POLICY_AUTOMATIC,
ST_PARAM_READWRITE);
+ /**
+ * StScrollView:hscrollbar-visible:
+ *
+ * Whether the horizontal #StScrollBar is visible.
+ */
props[PROP_HSCROLLBAR_VISIBLE] =
g_param_spec_boolean ("hscrollbar-visible",
"Horizontal Scrollbar Visibility",
TRUE,
ST_PARAM_READABLE);
+ /**
+ * StScrollView:vscrollbar-visible:
+ *
+ * Whether the vertical #StScrollBar is visible.
+ */
props[PROP_VSCROLLBAR_VISIBLE] =
g_param_spec_boolean ("vscrollbar-visible",
"Vertical Scrollbar Visibility",
TRUE,
ST_PARAM_READABLE);
+ /**
+ * StScrollView:enable-mouse-scrolling:
+ *
+ * Whether to enable automatic mouse wheel scrolling.
+ */
props[PROP_MOUSE_SCROLL] =
g_param_spec_boolean ("enable-mouse-scrolling",
"Enable Mouse Scrolling",
TRUE,
ST_PARAM_READWRITE);
+ /**
+ * StScrollView:overlay-scrollbars:
+ *
+ * Whether scrollbars are painted on top of the content.
+ */
props[PROP_OVERLAY_SCROLLBARS] =
g_param_spec_boolean ("overlay-scrollbars",
"Use Overlay Scrollbars",
iface->remove = st_scroll_view_remove;
}
+/**
+ * st_scroll_view_new:
+ *
+ * Create a new #StScrollView.
+ *
+ * Returns: (transfer full): a new #StScrollView
+ */
StWidget *
st_scroll_view_new (void)
{
* st_scroll_view_get_hscroll_bar:
* @scroll: a #StScrollView
*
- * Gets the horizontal scrollbar of the scrollbiew
+ * Gets the horizontal #StScrollBar of the #StScrollView.
*
- * Return value: (transfer none): the horizontal #StScrollBar
+ * Returns: (transfer none): the horizontal scrollbar
*/
ClutterActor *
st_scroll_view_get_hscroll_bar (StScrollView *scroll)
* st_scroll_view_get_vscroll_bar:
* @scroll: a #StScrollView
*
- * Gets the vertical scrollbar of the scrollbiew
+ * Gets the vertical scrollbar of the #StScrollView.
*
- * Return value: (transfer none): the vertical #StScrollBar
+ * Returns: (transfer none): the vertical #StScrollBar
*/
ClutterActor *
st_scroll_view_get_vscroll_bar (StScrollView *scroll)
return scroll->priv->vscroll;
}
+/**
+ * st_scroll_view_get_column_size:
+ * @scroll: a #StScrollView
+ *
+ * Get the step increment of the horizontal plane.
+ *
+ * Returns: the horizontal step increment
+ */
gfloat
st_scroll_view_get_column_size (StScrollView *scroll)
{
return column_size;
}
+/**
+ * st_scroll_view_set_column_size:
+ * @scroll: a #StScrollView
+ * @column_size: horizontal step increment
+ *
+ * Set the step increment of the horizontal plane to @column_size.
+ */
void
st_scroll_view_set_column_size (StScrollView *scroll,
gfloat column_size)
}
}
+/**
+ * st_scroll_view_get_row_size:
+ * @scroll: a #StScrollView
+ *
+ * Get the step increment of the vertical plane.
+ *
+ * Returns: the vertical step increment
+ */
gfloat
st_scroll_view_get_row_size (StScrollView *scroll)
{
return row_size;
}
+/**
+ * st_scroll_view_set_row_size:
+ * @scroll: a #StScrollView
+ * @row_size: vertical step increment
+ *
+ * Set the step increment of the vertical plane to @row_size.
+ */
void
st_scroll_view_set_row_size (StScrollView *scroll,
gfloat row_size)
}
}
+/**
+ * st_scroll_view_set_mouse_scrolling:
+ * @scroll: a #StScrollView
+ * @enabled: %TRUE or %FALSE
+ *
+ * Sets automatic mouse wheel scrolling to enabled or disabled.
+ */
void
st_scroll_view_set_mouse_scrolling (StScrollView *scroll,
gboolean enabled)
}
}
+/**
+ * st_scroll_view_get_mouse_scrolling:
+ * @scroll: a #StScrollView
+ *
+ * Get whether automatic mouse wheel scrolling is enabled or disabled.
+ *
+ * Returns: %TRUE if enabled, %FALSE otherwise
+ */
gboolean
st_scroll_view_get_mouse_scrolling (StScrollView *scroll)
{
* st_scroll_view_get_overlay_scrollbars:
* @scroll: A #StScrollView
*
- * Gets the value set by st_scroll_view_set_overlay_scrollbars().
+ * Gets whether scrollbars are painted on top of the content.
+ *
+ * Returns: %TRUE if enabled, %FALSE otherwise
*/
gboolean
st_scroll_view_get_overlay_scrollbars (StScrollView *scroll)
if (!initialized)
{
+ /**
+ * StScrollable:hadjustment:
+ *
+ * The horizontal #StAdjustment used by the #StScrollable.
+ *
+ * Implementations should override this property to provide read-write
+ * access to the #StAdjustment.
+ *
+ * JavaScript code may override this as demonstrated below:
+ *
+ * |[<!-- language="JavaScript" -->
+ * var MyScrollable = GObject.registerClass({
+ * Properties: {
+ * 'hadjustment': GObject.ParamSpec.override(
+ * 'hadjustment',
+ * St.Scrollable
+ * )
+ * }
+ * }, class MyScrollable extends St.Scrollable {
+ *
+ * get hadjustment() {
+ * return this._hadjustment || null;
+ * }
+ *
+ * set hadjustment(adjustment) {
+ * if (this.hadjustment === adjustment)
+ * return;
+ *
+ * this._hadjustment = adjustment;
+ * this.notify('hadjustment');
+ * }
+ * });
+ * ]|
+ */
g_object_interface_install_property (g_iface,
g_param_spec_object ("hadjustment",
"StAdjustment",
ST_TYPE_ADJUSTMENT,
ST_PARAM_READWRITE));
+ /**
+ * StScrollable:vadjustment:
+ *
+ * The vertical #StAdjustment used by the #StScrollable.
+ *
+ * Implementations should override this property to provide read-write
+ * access to the #StAdjustment.
+ *
+ * See #StScrollable:hadjustment for an example of how to override this
+ * property in JavaScript code.
+ */
g_object_interface_install_property (g_iface,
g_param_spec_object ("vadjustment",
"StAdjustment",
}
}
+/**
+ * st_scrollable_set_adjustments:
+ * @scrollable: a #StScrollable
+ * @hadjustment: the horizontal #StAdjustment
+ * @vadjustment: the vertical #StAdjustment
+ *
+ * This method should be implemented by classes implementing the #StScrollable
+ * interface.
+ *
+ * JavaScript code should do this by overriding the `vfunc_set_adjustments()`
+ * method.
+ */
void
st_scrollable_set_adjustments (StScrollable *scrollable,
StAdjustment *hadjustment,
/**
* st_scroll_bar_get_adjustments:
- * @hadjustment: (transfer none) (out) (optional) (nullable): location to store the horizontal adjustment, or %NULL
- * @vadjustment: (transfer none) (out) (optional) (nullable): location to store the vertical adjustment, or %NULL
+ * @hadjustment: (transfer none) (out) (optional): location to store the horizontal adjustment, or %NULL
+ * @vadjustment: (transfer none) (out) (optional): location to store the vertical adjustment, or %NULL
*
* Gets the adjustment objects that store the offsets of the scrollable widget
* into its possible scrolling area.
+ *
+ * This method should be implemented by classes implementing the #StScrollable
+ * interface.
+ *
+ * JavaScript code should do this by overriding the `vfunc_get_adjustments()`
+ * method.
*/
void
st_scrollable_get_adjustments (StScrollable *scrollable,
object_class->set_property = st_settings_set_property;
object_class->get_property = st_settings_get_property;
+ /**
+ * StSettings:enable-animations:
+ *
+ * Whether animations are enabled.
+ */
props[PROP_ENABLE_ANIMATIONS] = g_param_spec_boolean ("enable-animations",
"Enable animations",
"Enable animations",
TRUE,
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:primary-paste:
+ *
+ * Whether pasting from the `PRIMARY` selection is supported (eg. middle-click
+ * paste).
+ */
props[PROP_PRIMARY_PASTE] = g_param_spec_boolean ("primary-paste",
"Primary paste",
"Primary paste",
TRUE,
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:drag-threshold:
+ *
+ * The threshold before a drag operation begins.
+ */
props[PROP_DRAG_THRESHOLD] = g_param_spec_int ("drag-threshold",
"Drag threshold",
"Drag threshold",
0, G_MAXINT, 8,
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:font-name:
+ *
+ * The current font name.
+ */
props[PROP_FONT_NAME] = g_param_spec_string ("font-name",
"font name",
"font name",
"",
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:gtk-theme:
+ *
+ * The current GTK theme.
+ */
props[PROP_GTK_THEME] = g_param_spec_string ("gtk-theme",
- "GTK+ Theme",
- "GTK+ Theme",
+ "GTK Theme",
+ "GTK Theme",
"",
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:gtk-icon-theme:
+ *
+ * The current GTK icon theme
+ */
props[PROP_GTK_ICON_THEME] = g_param_spec_string ("gtk-icon-theme",
- "GTK+ Icon Theme",
- "GTK+ Icon Theme",
+ "GTK Icon Theme",
+ "GTK Icon Theme",
"",
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:magnifier-active:
+ *
+ * Whether the accessibility magnifier is active.
+ */
props[PROP_MAGNIFIER_ACTIVE] = g_param_spec_boolean("magnifier-active",
"Magnifier is active",
- "Weather the a11y magnifier is active",
+ "Whether the a11y magnifier is active",
FALSE,
ST_PARAM_READABLE);
+
+ /**
+ * StSettings:slow-down-factor:
+ *
+ * The slow-down factor applied to all animation durations.
+ */
props[PROP_SLOW_DOWN_FACTOR] = g_param_spec_double("slow-down-factor",
"Slow down factor",
"Factor applied to all animation durations",
/**
* st_settings_get:
*
- * Gets the #StSettings
+ * Gets the global #StSettings object.
*
- * Returns: (transfer none): a settings object
+ * Returns: (transfer none): the global #StSettings object
**/
StSettings *
st_settings_get (void)
* compare non-identically if they differ only by floating point rounding
* errors.
*
- * Return value: %TRUE if the two shadows are identical
+ * Returns: %TRUE if the two shadows are identical
*/
gboolean
st_shadow_equal (StShadow *shadow,
return helper;
}
+/**
+ * st_shadow_helper_update:
+ * @helper: a #StShadowHelper
+ * @source: a #ClutterActor
+ *
+ * Update @helper from @source.
+ */
void
st_shadow_helper_update (StShadowHelper *helper,
ClutterActor *source)
gobject_class->dispose = st_texture_cache_dispose;
gobject_class->finalize = st_texture_cache_finalize;
+ /**
+ * StTextureCache::icon-theme-changed:
+ * @self: a #StTextureCache
+ *
+ * Emitted when the icon theme is changed.
+ */
signals[ICON_THEME_CHANGED] =
g_signal_new ("icon-theme-changed",
G_TYPE_FROM_CLASS (klass),
NULL, NULL, NULL,
G_TYPE_NONE, 0);
+ /**
+ * StTextureCache::texture-file-changed:
+ * @self: a #StTextureCache
+ * @file: a #GFile
+ *
+ * Emitted when the source file of a texture is changed.
+ */
signals[TEXTURE_FILE_CHANGED] =
g_signal_new ("texture-file-changed",
G_TYPE_FROM_CLASS (klass),
/**
* st_texture_cache_bind_cairo_surface_property:
- * @cache:
+ * @cache: A #StTextureCache
* @object: A #GObject with a property @property_name of type #cairo_surface_t
* @property_name: Name of a property
*
* If the source object is destroyed, the texture will continue to show the last
* value of the property.
*
- * Return value: (transfer none): A new #GIcon
+ * Returns: (transfer none): A new #GIcon
*/
GIcon *
st_texture_cache_bind_cairo_surface_property (StTextureCache *cache,
/**
* ensure_request:
- * @cache:
+ * @cache: A #StTextureCache
* @key: A cache key
* @policy: Cache policy
* @request: (out): If no request is outstanding, one will be created and returned here
/**
* st_texture_cache_load_gicon:
- * @cache: The texture cache instance
- * @theme_node: (nullable): The #StThemeNode to use for colors, or NULL
+ * @cache: A #StTextureCache
+ * @theme_node: (nullable): The #StThemeNode to use for colors, or %NULL
* if the icon must not be recolored
* @icon: the #GIcon to load
* @size: Size of themed
* icon isn't loaded already, the texture will be filled
* asynchronously.
*
- * Return Value: (transfer none): A new #ClutterActor for the icon, or %NULL if not found
+ * Returns: (transfer none) (nullable): A new #ClutterActor for the icon, or %NULL if not found
*/
ClutterActor *
st_texture_cache_load_gicon (StTextureCache *cache,
/**
* st_texture_cache_load_file_async:
- * @cache: The texture cache instance
+ * @cache: A #StTextureCache
* @file: a #GFile of the image file from which to create a pixbuf
* @available_width: available width for the image, can be -1 if not limited
* @available_height: available height for the image, can be -1 if not limited
* size of zero. At some later point, either the image will be loaded successfully
* and at that point size will be negotiated, or upon an error, no image will be set.
*
- * Return value: (transfer none): A new #ClutterActor with no image loaded initially.
+ * Returns: (transfer none): A new #ClutterActor with no image loaded initially.
*/
ClutterActor *
st_texture_cache_load_file_async (StTextureCache *cache,
/**
* st_texture_cache_get_default:
*
- * Return value: (transfer none): The global texture cache
+ * Returns: (transfer none): The global texture cache
*/
StTextureCache*
st_texture_cache_get_default (void)
return instance;
}
+/**
+ * st_texture_cache_rescan_icon_theme:
+ *
+ * Rescan the current icon theme, if necessary.
+ *
+ * Returns: %TRUE if the icon theme has changed and needed to be reloaded.
+ */
gboolean
st_texture_cache_rescan_icon_theme (StTextureCache *cache)
{
/**
* StThemeContext:scale-factor:
*
- * The scaling factor used or high dpi scaling.
+ * The scaling factor used for HiDPI scaling.
*/
g_object_class_install_property (object_class,
PROP_SCALE_FACTOR,
g_param_spec_int ("scale-factor",
"Scale factor",
- "Integer scale factor used for high dpi scaling",
+ "Integer scale factor used for HiDPI scaling",
0, G_MAXINT, 1,
ST_PARAM_READWRITE));
+ /**
+ * StThemeContext::changed:
+ * @self: a #StThemeContext
+ *
+ * Emitted when the icon theme, font, resolution, scale factor or the current
+ * theme's custom stylesheets change.
+ */
signals[CHANGED] =
g_signal_new ("changed",
G_TYPE_FROM_CLASS (klass),
* This can be useful in testing scenarios, or if using StThemeContext
* with something other than #ClutterActor objects, but you generally
* should use st_theme_context_get_for_stage() instead.
+ *
+ * Returns: (transfer full): a new #StThemeContext
*/
StThemeContext *
st_theme_context_new (void)
*
* Gets a singleton theme context associated with the stage.
*
- * Return value: (transfer none): the singleton theme context for the stage
+ * Returns: (transfer none): the singleton theme context for the stage
*/
StThemeContext *
st_theme_context_get_for_stage (ClutterStage *stage)
/**
* st_theme_context_set_theme:
* @context: a #StThemeContext
+ * @theme: a #StTheme
*
* Sets the default set of theme stylesheets for the context. This theme will
* be used for the root node and for nodes descending from it, unless some other
*
* Gets the default theme for the context. See st_theme_context_set_theme()
*
- * Return value: (transfer none): the default theme for the context
+ * Returns: (transfer none): the default theme for the context
*/
StTheme *
st_theme_context_get_theme (StThemeContext *context)
* Sets the default font for the theme context. This is the font that
* is inherited by the root node of the tree of theme nodes. If the
* font is not overriden, then this font will be used. If the font is
- * partially modified (for example, with 'font-size: 110%', then that
+ * partially modified (for example, with 'font-size: 110%'), then that
* modification is based on this font.
*/
void
*
* Gets the default font for the theme context. See st_theme_context_set_font().
*
- * Return value: the default font for the theme context.
+ * Returns: the default font for the theme context.
*/
const PangoFontDescription *
st_theme_context_get_font (StThemeContext *context)
* context. For the node tree associated with a stage, this node represents
* styles applied to the stage itself.
*
- * Return value: (transfer none): the root node of the context's style tree
+ * Returns: (transfer none): the root node of the context's style tree
*/
StThemeNode *
st_theme_context_get_root_node (StThemeContext *context)
* Return an existing node matching @node, or if that isn't possible,
* @node itself.
*
- * Return value: (transfer none): a node with the same properties as @node
+ * Returns: (transfer none): a node with the same properties as @node
*/
StThemeNode *
st_theme_context_intern_node (StThemeContext *context,
*
* Return the current scale factor of @context.
*
- * Return value: a scale factor
+ * Returns: an integer scale factor
*/
int
st_theme_context_get_scale_factor (StThemeContext *context)
* @pseudo_class: (nullable): a whitespace-separated list of pseudo-classes
* (like 'hover' or 'visited') to match CSS rules against
*
- * Creates a new #StThemeNode. Once created, a node is immutable. Of any
+ * Creates a new #StThemeNode. Once created, a node is immutable. If any
* of the attributes of the node (like the @element_class) change the node
* and its child nodes must be destroyed and recreated.
*
- * Return value: (transfer full): the theme node
+ * Returns: (transfer full): a new #StThemeNode
*/
StThemeNode *
st_theme_node_new (StThemeContext *context,
*
* Gets the parent themed element node.
*
- * Return value: (transfer none): the parent #StThemeNode, or %NULL if this
- * is the root node of the tree of theme elements.
+ * Returns: (nullable) (transfer none): the parent #StThemeNode, or %NULL if
+ * this is the root node of the tree of theme elements.
*/
StThemeNode *
st_theme_node_get_parent (StThemeNode *node)
*
* Gets the theme stylesheet set that styles this node
*
- * Return value: (transfer none): the theme stylesheet set
+ * Returns: (transfer none): the theme stylesheet set
*/
StTheme *
st_theme_node_get_theme (StThemeNode *node)
return node->theme;
}
+/**
+ * st_theme_node_get_element_type:
+ * @node: a #StThemeNode
+ *
+ * Get the element #GType for @node.
+ *
+ * Returns: the element type
+ */
GType
st_theme_node_get_element_type (StThemeNode *node)
{
return node->element_type;
}
+/**
+ * st_theme_node_get_element_id:
+ * @node: a #StThemeNode
+ *
+ * Get the unqiue element ID for @node.
+ *
+ * Returns: (transfer none): the element's ID
+ */
const char *
st_theme_node_get_element_id (StThemeNode *node)
{
/**
* st_theme_node_get_element_classes:
+ * @node: a #StThemeNode
+ *
+ * Get the list of element classes for @node.
*
* Returns: (transfer none): the element's classes
*/
/**
* st_theme_node_get_pseudo_classes:
+ * @node: a #StThemeNode
+ *
+ * Get the list of pseudo-classes for @node (eg. `:focused`).
*
* Returns: (transfer none): the element's pseudo-classes
*/
* the same CSS rules and have the same style properties. However, two
* nodes that have ended up with identical style properties do not
* necessarily compare equal.
- * In detail, @node_a and @node_b are considered equal iff
- * <itemizedlist>
- * <listitem>
- * <para>they share the same #StTheme and #StThemeContext</para>
- * </listitem>
- * <listitem>
- * <para>they have the same parent</para>
- * </listitem>
- * <listitem>
- * <para>they have the same element type</para>
- * </listitem>
- * <listitem>
- * <para>their id, class, pseudo-class and inline-style match</para>
- * </listitem>
- * </itemizedlist>
+ *
+ * In detail, @node_a and @node_b are considered equal if and only if:
+ *
+ * - they share the same #StTheme and #StThemeContext
+ * - they have the same parent
+ * - they have the same element type
+ * - their id, class, pseudo-class and inline-style match
*
* Returns: %TRUE if @node_a equals @node_b
*/
return TRUE;
}
+/**
+ * st_theme_node_hash:
+ * @node: a #StThemeNode
+ *
+ * Converts @node to a hash value.
+ *
+ * Returns: a hash value corresponding to @node
+ */
guint
st_theme_node_hash (StThemeNode *node)
{
*
* See also st_theme_node_get_color(), which provides a simpler API.
*
- * Return value: %TRUE if the property was found in the properties for this
+ * Returns: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.)
*/
gboolean
*
* See also st_theme_node_get_double(), which provides a simpler API.
*
- * Return value: %TRUE if the property was found in the properties for this
+ * Returns: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.)
*/
gboolean
* Generically looks up a property containing a single time value,
* which is converted to milliseconds.
*
- * Return value: %TRUE if the property was found in the properties for this
+ * Returns: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.)
*/
gboolean
* and lets you handle the case where the theme does not specify the
* indicated value.
*
- * Return value: the value found. If @property_name is not
+ * Returns: the value found. If @property_name is not
* found, a warning will be logged and 0 will be returned.
*/
gdouble
*
* See also st_theme_node_get_url(), which provides a simpler API.
*
- * Return value: %TRUE if the property was found in the properties for this
+ * Returns: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.)
*/
gboolean
* and lets you handle the case where the theme does not specify the
* indicated value.
*
- * Returns: (transfer full): the newly allocated value if found.
+ * Returns: (nullable) (transfer full): the newly allocated value if found.
* If @property_name is not found, a warning will be logged and %NULL
* will be returned.
*/
*
* See also st_theme_node_get_length(), which provides a simpler API.
*
- * Return value: %TRUE if the property was found in the properties for this
+ * Returns: %TRUE if the property was found in the properties for this
* theme node (or in the properties of parent nodes when inheriting.)
*/
gboolean
* this does not print a warning if the property is not found; it just
* returns 0.
*
- * See also st_theme_node_lookup_length(), which provides more options.
+ * See also st_theme_node_lookup_length(), which provides more options. The
+ * returned value is in physical pixels, as opposed to logical pixels.
*
- * Return value: the length, in pixels, or 0 if the property was not found.
+ * Returns: the length, in pixels, or 0 if the property was not found.
*/
gdouble
st_theme_node_get_length (StThemeNode *node,
node->height = node->min_height;
}
+/**
+ * st_theme_node_get_border_width:
+ * @node: a #StThemeNode
+ * @side: a #StCorner
+ *
+ * Get the border width for @node on @side, in physical pixels.
+ *
+ * Returns: the border width in physical pixels
+ */
int
st_theme_node_get_border_width (StThemeNode *node,
StSide side)
return node->border_width[side];
}
+/**
+ * st_theme_node_get_border_radius:
+ * @node: a #StThemeNode
+ * @corner: a #StCorner
+ *
+ * Get the border radius for @node at @corner, in physical pixels.
+ *
+ * Returns: the border radius in physical pixels
+ */
int
st_theme_node_get_border_radius (StThemeNode *node,
StCorner corner)
return node->border_radius[corner];
}
+/**
+ * st_theme_node_get_outline_width:
+ * @node: a #StThemeNode
+ *
+ * Get the width of the outline for @node, in physical pixels.
+ *
+ * Returns: the width in physical pixels
+ */
int
st_theme_node_get_outline_width (StThemeNode *node)
{
*color = node->outline_color;
}
+/**
+ * st_theme_node_get_width:
+ * @node: a #StThemeNode
+ *
+ * Get the width for @node, in physical pixels.
+ *
+ * Returns: the width in physical pixels
+ */
int
st_theme_node_get_width (StThemeNode *node)
{
return node->width;
}
+/**
+ * st_theme_node_get_height:
+ * @node: a #StThemeNode
+ *
+ * Get the height for @node, in physical pixels.
+ *
+ * Returns: the height in physical pixels
+ */
int
st_theme_node_get_height (StThemeNode *node)
{
return node->height;
}
+/**
+ * st_theme_node_get_min_width:
+ * @node: a #StThemeNode
+ *
+ * Get the minimum width for @node, in physical pixels.
+ *
+ * Returns: the minimum width in physical pixels
+ */
int
st_theme_node_get_min_width (StThemeNode *node)
{
return node->min_width;
}
+/**
+ * st_theme_node_get_min_height:
+ * @node: a #StThemeNode
+ *
+ * Get the minimum height for @node, in physical pixels.
+ *
+ * Returns: the minimum height in physical pixels
+ */
int
st_theme_node_get_min_height (StThemeNode *node)
{
return node->min_height;
}
+/**
+ * st_theme_node_get_max_width:
+ * @node: a #StThemeNode
+ *
+ * Get the maximum width for @node, in physical pixels.
+ *
+ * Returns: the maximum width in physical pixels
+ */
int
st_theme_node_get_max_width (StThemeNode *node)
{
return node->max_width;
}
+/**
+ * st_theme_node_get_max_height:
+ * @node: a #StThemeNode
+ *
+ * Get the maximum height for @node, in physical pixels.
+ *
+ * Returns: the maximum height in physical pixels
+ */
int
st_theme_node_get_max_height (StThemeNode *node)
{
*color = node->border_color[side];
}
+/**
+ * st_theme_node_get_padding:
+ * @node: a #StThemeNode
+ * @side: a #StSide
+ *
+ * Get the padding for @node on @side, in physical pixels. This corresponds to
+ * the CSS properties such as `padding-top`.
+ *
+ * Returns: the padding size in physical pixels
+ */
double
st_theme_node_get_padding (StThemeNode *node,
StSide side)
return node->padding[side];
}
+/**
+ * st_theme_node_get_margin:
+ * @node: a #StThemeNode
+ * @side: a #StSide
+ *
+ * Get the margin for @node on @side, in physical pixels. This corresponds to
+ * the CSS properties such as `margin-top`.
+ *
+ * Returns: the margin size in physical pixels
+ */
double
st_theme_node_get_margin (StThemeNode *node,
StSide side)
return factor * node->transition_duration;
}
+/**
+ * st_theme_node_get_icon_style:
+ * @node: a #StThemeNode
+ *
+ * Get the icon style for @node (eg. symbolic, regular). This corresponds to the
+ * special `-st-icon-style` CSS property.
+ *
+ * Returns: the icon style for @node
+ */
StIconStyle
st_theme_node_get_icon_style (StThemeNode *node)
{
return ST_ICON_STYLE_REQUESTED;
}
+/**
+ * st_theme_node_get_text_decoration
+ * @node: a #StThemeNode
+ *
+ * Get the text decoration for @node (eg. underline, line-through, etc).
+ *
+ * Returns: the text decoration for @node
+ */
StTextDecoration
st_theme_node_get_text_decoration (StThemeNode *node)
{
return 0;
}
+/**
+ * st_theme_node_get_text_align:
+ * @node: a #StThemeNode
+ *
+ * Get the text alignment of @node.
+ *
+ * Returns: the alignment of text for @node
+ */
StTextAlign
st_theme_node_get_text_align(StThemeNode *node)
{
* st_theme_node_get_letter_spacing:
* @node: a #StThemeNode
*
- * Gets the value for the letter-spacing style property, in pixels.
+ * Gets the value for the letter-spacing style property, in physical pixels.
*
- * Return value: the value of the letter-spacing property, if
+ * Returns: the value of the letter-spacing property, if
* found, or zero if such property has not been found.
*/
gdouble
return TRUE;
}
+/**
+ * st_theme_node_get_font:
+ * @node: a #StThemeNode
+ *
+ * Get the current font of @node as a #PangoFontDescription
+ *
+ * Returns: (transfer none): the current font
+ */
const PangoFontDescription *
st_theme_node_get_font (StThemeNode *node)
{
return node->font_desc;
}
+/**
+ * st_theme_node_get_font_features:
+ * @node: a #StThemeNode
+ *
+ * Get the CSS font-features for @node.
+ *
+ * Returns: (transfer full): font-features as a string
+ */
gchar *
st_theme_node_get_font_features (StThemeNode *node)
{
*
* Gets the value for the border-image style property
*
- * Return value: (transfer none): the border image, or %NULL
+ * Returns: (transfer none): the border image, or %NULL
* if there is no border image.
*/
StBorderImage *
* st_theme_node_get_horizontal_padding:
* @node: a #StThemeNode
*
- * Gets the total horizonal padding (left + right padding)
+ * Gets the total horizonal padding (left + right padding), in physical pixels.
*
- * Return value: the total horizonal padding
- * in pixels
+ * Returns: the total horizonal padding in physical pixels
*/
double
st_theme_node_get_horizontal_padding (StThemeNode *node)
* st_theme_node_get_vertical_padding:
* @node: a #StThemeNode
*
- * Gets the total vertical padding (top + bottom padding)
+ * Gets the total vertical padding (top + bottom padding), in physical pixels.
*
- * Return value: the total vertical padding
- * in pixels
+ * Returns: the total vertical padding in physical pixels
*/
double
st_theme_node_get_vertical_padding (StThemeNode *node)
*
* See also st_theme_node_get_shadow(), which provides a simpler API.
*
- * Return value: %TRUE if the property was found in the properties for this
- * theme node (or in the properties of parent nodes when inheriting.), %FALSE
- * if the property was not found, or was explicitly set to 'none'.
+ * Returns: %TRUE if the property was found in the properties for this
+ * theme node (or in the properties of parent nodes when inheriting.), %FALSE
+ * if the property was not found, or was explicitly set to 'none'.
*/
gboolean
st_theme_node_lookup_shadow (StThemeNode *node,
*
* See also st_theme_node_lookup_shadow (), which provides more options.
*
- * Return value: (transfer full): the shadow, or %NULL if the property was not found.
+ * Returns: (nullable) (transfer full): the shadow, or %NULL if the property was
+ * not found.
*/
StShadow *
st_theme_node_get_shadow (StThemeNode *node,
*
* Gets the value for the box-shadow style property
*
- * Return value: (transfer none): the node's shadow, or %NULL
+ * Returns: (nullable) (transfer none): the node's shadow, or %NULL
* if node has no shadow
*/
StShadow *
*
* Gets the value for the -st-background-image-shadow style property
*
- * Return value: (transfer none): the node's background image shadow, or %NULL
- * if node has no such shadow
+ * Returns: (nullable) (transfer none): the node's background image shadow, or
+ * %NULL if node has no such shadow
*/
StShadow *
st_theme_node_get_background_image_shadow (StThemeNode *node)
*
* Gets the value for the text-shadow style property
*
- * Return value: (transfer none): the node's text-shadow, or %NULL
+ * Returns: (nullable) (transfer none): the node's text-shadow, or %NULL
* if node has no text-shadow
*/
StShadow *
* Gets the colors that should be used for colorizing symbolic icons according
* the style of this node.
*
- * Return value: (transfer none): the icon colors to use for this theme node
+ * Returns: (transfer none): the icon colors to use for this theme node
*/
StIconColors *
st_theme_node_get_icon_colors (StThemeNode *node)
* Tests if two theme nodes have the same borders and padding; this can be
* used to optimize having to relayout when the style applied to a Clutter
* actor changes colors without changing the geometry.
+ *
+ * Returns: %TRUE if equal, %FALSE otherwise
*/
gboolean
st_theme_node_geometry_equal (StThemeNode *node,
* for @other. Note that in some cases this function may return %TRUE even
* if there is no visible difference in the painting.
*
- * Return value: %TRUE if the two theme nodes paint identically. %FALSE if the
+ * Returns: %TRUE if the two theme nodes paint identically. %FALSE if the
* two nodes potentially paint differently.
*/
gboolean
return TRUE;
}
+/**
+ * st_theme_node_to_string:
+ * @node: a #StThemeNode
+ *
+ * Serialize @node to a string of its #GType name, CSS ID, classes and
+ * pseudo-classes.
+ *
+ * Returns: the serialized theme node
+ */
gchar *
st_theme_node_to_string (StThemeNode *node)
{
* accessors for standard CSS properties that add caching and handling of various
* details of the CSS specification. #StThemeNode also has convenience functions to help
* in implementing a #ClutterActor with borders and padding.
+ *
+ * Note that pixel measurements take the #StThemeContext:scale-factor into
+ * account so all values are in physical pixels, as opposed to logical pixels.
+ * Physical pixels correspond to actor sizes, not necessarily to pixels on
+ * display devices (eg. when `scale-monitor-framebuffer` is enabled).
*/
typedef struct _StTheme StTheme;
#define ST_TYPE_THEME_NODE (st_theme_node_get_type ())
G_DECLARE_FINAL_TYPE (StThemeNode, st_theme_node, ST, THEME_NODE, GObject)
+/**
+ * StSide:
+ * @ST_SIDE_TOP: The top side.
+ * @ST_SIDE_RIGHT: The right side.
+ * @ST_SIDE_BOTTOM: The bottom side.
+ * @ST_SIDE_LEFT: The left side.
+ *
+ * Used to target a particular side of a #StThemeNode element.
+ */
typedef enum {
ST_SIDE_TOP,
ST_SIDE_RIGHT,
ST_SIDE_LEFT
} StSide;
+/**
+ * StCorner:
+ * @ST_CORNER_TOPLEFT: The top-right corner.
+ * @ST_CORNER_TOPRIGHT: The top-right corner.
+ * @ST_CORNER_BOTTOMRIGHT: The bottom-right corner.
+ * @ST_CORNER_BOTTOMLEFT: The bottom-left corner.
+ *
+ * Used to target a particular corner of a #StThemeNode element.
+ */
typedef enum {
ST_CORNER_TOPLEFT,
ST_CORNER_TOPRIGHT,
} StCorner;
/* These are the CSS values; that doesn't mean we have to implement blink... */
+/**
+ * StTextDecoration:
+ * @ST_TEXT_DECORATION_: Text is underlined
+ * @ST_TEXT_DECORATION_OVERLINE: Text is overlined
+ * @ST_TEXT_DECORATION_LINE_THROUGH: Text is striked out
+ * @ST_TEXT_DECORATION_BLINK: Text blinks
+ *
+ * Flags used to determine the decoration of text.
+ *
+ * Not that neither %ST_TEXT_DECORATION_OVERLINE or %ST_TEXT_DECORATION_BLINK
+ * are implemented, currently.
+ */
typedef enum {
ST_TEXT_DECORATION_UNDERLINE = 1 << 0,
ST_TEXT_DECORATION_OVERLINE = 1 << 1,
ST_TEXT_DECORATION_BLINK = 1 << 3
} StTextDecoration;
+/**
+ * StTextAlign:
+ * @ST_TEXT_ALIGN_LEFT: Text is aligned at the beginning of the label.
+ * @ST_TEXT_ALIGN_CENTER: Text is aligned in the middle of the label.
+ * @ST_TEXT_ALIGN_RIGHT: Text is aligned at the end of the label.
+ * @ST_GRADIENT_JUSTIFY: Text is justified in the label.
+ *
+ * Used to align text in a label.
+ */
typedef enum {
ST_TEXT_ALIGN_LEFT = PANGO_ALIGN_LEFT,
ST_TEXT_ALIGN_CENTER = PANGO_ALIGN_CENTER,
ST_TEXT_ALIGN_JUSTIFY
} StTextAlign;
+/**
+ * StGradientType:
+ * @ST_GRADIENT_NONE: No gradient.
+ * @ST_GRADIENT_VERTICAL: A vertical gradient.
+ * @ST_GRADIENT_HORIZONTAL: A horizontal gradient.
+ * @ST_GRADIENT_RADIAL: Lookup the style requested in the icon name.
+ *
+ * Used to specify options when rendering gradients.
+ */
typedef enum {
ST_GRADIENT_NONE,
ST_GRADIENT_VERTICAL,
ST_GRADIENT_RADIAL
} StGradientType;
+/**
+ * StIconStyle:
+ * @ST_ICON_STYLE_REQUESTED: Lookup the style requested in the icon name.
+ * @ST_ICON_STYLE_REGULAR: Try to always load regular icons, even when symbolic
+ * icon names are given.
+ * @ST_ICON_STYLE_SYMBOLIC: Try to always load symbolic icons, even when regular
+ * icon names are given.
+ *
+ * Used to specify options when looking up icons.
+ */
typedef enum {
ST_ICON_STYLE_REQUESTED,
ST_ICON_STYLE_REGULAR,
g_hash_table_insert (theme->files_by_stylesheet, stylesheet, file);
}
+/**
+ * st_theme_load_stylesheet:
+ * @theme: a #StTheme
+ * @file: a #GFile
+ * @error: (optional): a #GError
+ *
+ * Load the stylesheet associated with @file.
+ *
+ * Returns: %TRUE if successful
+ */
gboolean
st_theme_load_stylesheet (StTheme *theme,
GFile *file,
return TRUE;
}
+/**
+ * st_theme_unload_stylesheet:
+ * @theme: a #StTheme
+ * @file: a #GFile
+ *
+ * Unload the stylesheet associated with @file. If @file was not loaded this
+ * function does nothing.
+ */
void
st_theme_unload_stylesheet (StTheme *theme,
GFile *file)
* st_theme_get_custom_stylesheets:
* @theme: an #StTheme
*
+ * Get a list of the stylesheet files loaded with st_theme_load_stylesheet().
+ *
* Returns: (transfer full) (element-type GFile): the list of stylesheet files
* that were loaded with st_theme_load_stylesheet()
*/
* @default_stylesheet: The lowest priority stylesheet, representing global default styling;
* this is associated with the CSS "user agent" stylesheet, may be %NULL
*
- * Return value: the newly created theme object
+ * Returns: the newly created theme object
**/
StTheme *
st_theme_new (GFile *application_stylesheet,
* Note: it is a fatal error to call this on a widget that is
* not been added to a stage.
*
- * Return value: (transfer none): the theme node for the widget.
+ * Returns: (transfer none): the theme node for the widget.
* This is owned by the widget. When attributes of the widget
* or the environment that affect the styling change (for example
* the style_class property of the widget), it will be recreated,
* node hasn't been computed. If %NULL is returned, then ::style-changed
* will be reliably emitted before the widget is allocated or painted.
*
- * Return value: (transfer none): the theme node for the widget.
+ * Returns: (transfer none): the theme node for the widget.
* This is owned by the widget. When attributes of the widget
* or the environment that affect the styling change (for example
* the style_class property of the widget), it will be recreated,
ST_PARAM_READWRITE);
/**
- * ClutterActor:label-actor:
+ * StWidget:label-actor:
*
* An actor that labels this widget.
*/
* StWidget::popup-menu:
* @widget: the #StWidget
*
- * Emitted when the user has requested a context menu (eg, via a
- * keybinding)
+ * Emitted when the user has requested a context menu (eg, via a keybinding)
*/
signals[POPUP_MENU] =
g_signal_new ("popup-menu",
*
* Get the current inline style string. See st_widget_set_style().
*
- * Returns: The inline style string, or %NULL. The string is owned by the
- * #StWidget and should not be modified or freed.
+ * Returns: (transfer none) (nullable): The inline style string, or %NULL. The
+ * string is owned by the #StWidget and should not be modified or freed.
*/
const gchar*
st_widget_get_style (StWidget *actor)
* st_widget_ensure_style:
* @widget: A #StWidget
*
- * Ensures that @widget has read its style information.
- *
+ * Ensures that @widget has read its style information and propagated any
+ * changes to its children.
*/
void
st_widget_ensure_style (StWidget *widget)
* st_widget_get_track_hover:
* @widget: A #StWidget
*
- * Returns the current value of the track-hover property. See
+ * Returns the current value of the #StWidget:track-hover property. See
* st_widget_set_track_hover() for more information.
*
* Returns: current value of track-hover on @widget
* st_widget_popup_menu:
* @self: A #StWidget
*
- * Asks the widget to pop-up a context menu.
+ * Asks the widget to pop-up a context menu by emitting #StWidget::popup-menu.
*/
void
st_widget_popup_menu (StWidget *self)
* time, using a %NULL @from, which should cause it to reset the focus
* to the first available widget in the given direction.
*
- * Return value: %TRUE if clutter_actor_grab_key_focus() has been
+ * Returns: %TRUE if clutter_actor_grab_key_focus() has been
* called on an actor. %FALSE if not.
*/
gboolean
* includes the class name and actor name (if any), plus if @actor
* is an #StWidget, its style class and pseudo class names.
*
- * Return value: the debug name.
+ * Returns: the debug name.
*/
char *
st_describe_actor (ClutterActor *actor)
*
* Gets the label that identifies @widget if it is defined
*
- * Return value: (transfer none): the label that identifies the widget
+ * Returns: (transfer none): the label that identifies the widget
*/
ClutterActor *
st_widget_get_label_actor (StWidget *widget)
* Gets the accessible name for this widget. See
* st_widget_set_accessible_name() for more information.
*
- * Return value: a character string representing the accessible name
+ * Returns: a character string representing the accessible name
* of the widget.
*/
const gchar *
* Gets the #AtkRole for this widget. See
* st_widget_set_accessible_role() for more information.
*
- * Return value: accessible #AtkRole for this widget
+ * Returns: accessible #AtkRole for this widget
*/
AtkRole
st_widget_get_accessible_role (StWidget *widget)
#define ST_TYPE_WIDGET (st_widget_get_type ())
G_DECLARE_DERIVABLE_TYPE (StWidget, st_widget, ST, WIDGET, ClutterActor)
+/**
+ * StDirectionType:
+ * @ST_DIR_TAB_FORWARD: Move forward.
+ * @ST_DIR_TAB_BACKWARD: Move backward.
+ * @ST_DIR_UP: Move up.
+ * @ST_DIR_DOWN: Move down.
+ * @ST_DIR_LEFT: Move left.
+ * @ST_DIR_RIGHT: Move right.
+ *
+ * Enumeration for focus direction.
+ */
typedef enum
{
ST_DIR_TAB_FORWARD,
projects / gnome-shell.git / commitdiff